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XMLTV Grabber Command-Line Parameters 


This document describes the command-line interface to the xmitv grabbers. It contains the parameters that are common between 
many grabbers. Each grabber may support additional parameters apart from the ones listed below. 


All grabbers shall support a --description parameter. It shall print a description that identifies the grabber: 


ies 


Example: 


The command-line parameters are divided into a number of groups called capabilities. Each capability has a name and defines a 
set of parameters that all grabbers that claim to implement that particular capability must support. 


To list the capabilities that a grabber supports, call the grabber with a single parameter: --capabilities. The grabber shall then 
respond by printing a list of all the capabilities that it supports to stdout, one capability per line, and then exiting with an exit code 
of 0. It must be possible to run the grabber with the --capabilities parameter without any prior configuration. 


Each section below describes which command-line parameters that capability includes. 


baseline 


If the grabber claims to implement the baseline capability, it must support the following command-line options when grabbing data: 


Redirect the xmitv output to the specified file. Otherwise output goes to stdout. This option is mostly there for Windows where 
there can be strange difficulties redirecting stdout. 


Supply data for X days. Each grabber may have an upper limit to the number of days that it can retum data for. If Xis larger than 
that limit, the grabber shall retum no data for the days that it lacks data for, print a waring to stderr, and exit with an error-code. 
See XmitvErrorCodes. 


In other words, if too many days are requested, the grabber will retum data for as many days as it can. 
The default number of days is 'as many as possible’. 


The grabber shall read all configuration data from the specified file. 


A grabber that claims to support the baseline capability must also be able to download data without any command-ine options 

apart from the ones listed above. All other information must be supplied in the configuration stage. 

Ideally, default values should be provided within the grabber so it can be run without any command-line options at all. 

The grabber must output data that adheres to the XmltvFormat with the following additional requirements: 

= All start- and stoptimes must include a timeofiset (e.g. +0100). Timezones (e.g. EST) are not permitted. 

= The data must contain exactly one <channel> entry for each channel mentioned in the file. 

= The data must not contain <channel> entries for channels that are not included in the data. 

= All xmitvids must match the regexp /*- O-91+(\. [-a-zA-20-9]+) +$/. 

= Ifthe grabber is first run with --offset 1 and then with t 2 --days 1, then the two datasets retumed must not 
overlap in time. By concatenating the two datasets, the result shall be identical to the output provided by --o: 
In practice this means the first programme output should be that which starts within the requested date range (i.e. not one 
which started yesterday). 

= Days should run from midnight to midnight - some data sources run from 06:00 - 06:00 so will need some adjustment. 


set 1 --days 2. 


manualconfig 


The manualconfig capability means that the grabber implements a configuration procedure where it asks the user a set of 
questions using the XVMLTV::Ask library. This library currently has two implementations: one to prompt on the terminal and one to 
ask graphically with a Perl/Tk interface. 


Allow the user to answer questions regarding the operation of the grabber. This can include usernames, passwords and lineup and 
it should also include a way for the user to specify which channels he wants to download data for. 


If this parameter is combined with -config-file, the configuration is written to the specified file. 


apiconfig 
The grabber shall sup} 


See XmitvConfigurationApi for a more detailed explanation and examples. 


share 
The grabber supports the following commancline option: 


sharedir specifies the location of the metadata for the grabber. For a properly installed grabber, this parameter should not be 
necessary to use. 


cache 
The grabber can cache the response to HTTP-requests in a file and reuse them without contacting the server again. This is useful if 
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the grabber is run multiple times or when doing tests. Note that some grabbers may retum the wrong result if a cachefile from a 
previous day is specified. 


Store the cache in cachefile. 


preferredmethod 


The grabber can tell the application how it prefers to be called in order to download data as efficiently as possible. 

If the grabber does not support the preferredmethod capability, the calling application shall assume that the consumed bandwidth 
is proportional to the number of days of data that is requested. It is therefore more efficient to download data for only the days that 
the application wants data. 


Prints a single word to stdout (?) that tells the calling application that the grabber prefers to be used in a specific way. By calling 
the grabber in this way, the calling application can make sure that the grabber uses as little bandwidth as possible. 


Available responses: 


allatonce 


The grabber downloads data in a single chunk and filters out the requested days. This means that it is more efficient to call this 
grabber once with a long period instead of several times with short periods. For example: If the application needs data for day 1 and 
5, it should call the grabber with 


Additional responses may be defined in the future. If the application does not understand the response, it shall act as if the grabber 
did not support the preferredmethod capability. 


Proposed Capabilities 


This section describes a number of capabilities that have been discussed on the xmltv mailing list, but that no grabber has 
implemented yet and the details may change. 


newchannels 


The newchannels capability means that the grabber can notify a PVR application if it can supply data for channels that weren't 
available when the grabber was last configured. The behaviour of this mechanism can be controlled with the following command-line 
parameter: 


“add" means that the grabber shall automatically supply data for all new channels without informing the PVR application. 
"ignore" means that the grabber shall ignore any new channels until the grabber is reconfigured. 


“notify" means that the grabber shall tell the PVR application that there are new channels available by exiting with a special error- 
code after outputting the data for all the configured channels. See XmitvErrorCodes. 


The default value for --channe1-updates is "ignore". This is also the behaviour implemented by all grabbers that don't implement the 
newchannels capability. 


{ I wonder if it mak . Need to think about this some more. 


channelnumberremapping 
The grabber can change the channel number associated with each channel. This is described in XmltvConfigurationFile. 


lineups 
See LineupProposal, LineupProposal2, NoLineupProposal. 
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